home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / EventHndlr.3 < prev    next >
Text File  |  1994-09-20  |  4KB  |  133 lines
  1.  
  2.  
  3.  
  4. Tk_CreateEventHandler(3T)k Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_CreateEventHandler,  Tk_DeleteEventHandler  -   associate
  12.      procedure callback with an X event
  13.  
  14. SYNOPSIS
  15.      #include <tk.h>
  16.  
  17.      Tk_CreateEventHandler(_t_k_w_i_n, _m_a_s_k, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  18.  
  19.      Tk_DeleteEventHandler(_t_k_w_i_n, _m_a_s_k, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  20.  
  21. ARGUMENTS
  22.      Tk_Window       _t_k_w_i_n        (in)      Token for  window  in
  23.                                             which    events   may
  24.                                             occur.
  25.  
  26.      unsigned long   _m_a_s_k         (in)      Bit-mask  of   events
  27.                                             (such     as     But-
  28.                                             tonPressMask)     for
  29.                                             which  _p_r_o_c should be
  30.                                             called.
  31.  
  32.      Tk_EventProc    *_p_r_o_c        (in)      Procedure  to  invoke
  33.                                             whenever  an event in
  34.                                             _m_a_s_k  occurs  in  the
  35.                                             window    given    by
  36.                                             _t_k_w_i_n.
  37.  
  38.      ClientData      _c_l_i_e_n_t_D_a_t_a   (in)      Arbitrary    one-word
  39.                                             value   to   pass  to
  40.                                             _p_r_o_c.
  41. _________________________________________________________________
  42.  
  43.  
  44. DESCRIPTION
  45.      Tk_CreateEventHandler arranges for _p_r_o_c to be invoked in the
  46.      future  whenever  one  of  the event types specified by _m_a_s_k
  47.      occurs in the window specified by _t_k_w_i_n.   The  callback  to
  48.      _p_r_o_c  will  be  made  by Tk_HandleEvent; this mechanism only
  49.      works   in   programs   that   dispatch    events    through
  50.      Tk_HandleEvent  (or  through  other  Tk procedures that call
  51.      Tk_HandleEvent, such as Tk_DoOneEvent or Tk_MainLoop).
  52.  
  53.      _P_r_o_c should have arguments and result that  match  the  type
  54.      Tk_EventProc:
  55.           typedef void Tk_EventProc(
  56.                ClientData _c_l_i_e_n_t_D_a_t_a,
  57.                XEvent *_e_v_e_n_t_P_t_r);
  58.      The _c_l_i_e_n_t_D_a_t_a parameter to _p_r_o_c is a copy of the _c_l_i_e_n_t_D_a_t_a
  59.      argument  given  to  Tk_CreateEventHandler when the callback
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_CreateEventHandler(3T)k Library Procedures
  71.  
  72.  
  73.  
  74.      was created.  Typically, _c_l_i_e_n_t_D_a_t_a points to a data  struc-
  75.      ture  containing  application-specific information about the
  76.      window in which the event occurred.  _E_v_e_n_t_P_t_r is  a  pointer
  77.      to  the  X event, which will be one of the ones specified in
  78.      the _m_a_s_k argument to Tk_CreateEventHandler.
  79.  
  80.      Tk_DeleteEventHandler may be called to delete a  previously-
  81.      created  event  handler:   it  deletes  the first handler it
  82.      finds that is associated with _t_k_w_i_n and  matches  the  _m_a_s_k,
  83.      _p_r_o_c,  and _c_l_i_e_n_t_D_a_t_a arguments.  If no such handler exists,
  84.      then  Tk_EventHandler  returns   without   doing   anything.
  85.      Although  Tk  supports  it, it's probably a bad idea to have
  86.      more than one callback with the same _m_a_s_k, _p_r_o_c, and _c_l_i_e_n_t_-
  87.      _D_a_t_a  arguments.   When  a  window  is  deleted  all  of its
  88.      handlers will be deleted automatically;  in this case  there
  89.      is no need to call Tk_DeleteEventHandler.
  90.  
  91.      If mutliple handlers are declared for the  same  type  of  X
  92.      event  on the same window, then the handlers will be invoked
  93.      in the order they were created.
  94.  
  95.  
  96. KEYWORDS
  97.      bind, callback, event, handler
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.